CarbonCopy XML attachment
The carbonCopy attachment works by detecting and extracting CC addresses from a Letter (the Primary Letter) and generating copies of the letter (the Copy Letters) for each CC address found.
Copy Letters are submitted into HybridMail pre-pended with the specified Cover Sheet. This should be a single-sheet PDF file with a blank address area and simple text content e.g. "Please see attached letter".
N.B. If you use conditions based on scanned text to control the processing flow, it is always the Primary Letter that is scanned for text, not the respective Copy Letter.
Schema
<mkzAttachment type="carbonCopy">
<onSubmit>
<ccAddresses identifier="identifier-name" [accuracy="all|any"] [failAction="reject"] />
<ccSingleAddress identifier="identifier-name" [accuracy="all|any"] [failAction="reject"] />
<coverLetterFolder>path-to-cover-letters</coverLetterFolder>
<coverLetter>cover-letter-filename</coverLetter>
<stripAttachments [stripSupplements="true|false"] />
<ccTemplate>template-ID</ccTemplate>
</onSubmit>
<onRelease>
<loadCustomData/>
<makePdfFileCopy folderName="identifier-name1" fileName="identifier-name2" [includeUnique="random|time|timeMs"] >
</makePdfFileCopy>
</onRelease>
</mkzAttachment>
The XML can be executed only during the OnSubmit phase.
The following elements are supported. There can be multiple instances of any of these
<ccAddresses> Specifies an identifier containing all the text to examine for CC addresses.
The scan attribute can also be used here, but an identifier is more useful because it supports the multiPage attribute, which is likely to be needed for CC address scanning. An address will be recognised as a CC address if it is prefixed with one of the markers:
CC: generic copy address.
CCX: copy address where attachments should be removed from the copy letter prior to posting.
CCE: copy address where copy letter should be sent by Electronic Delivery.
<ccAddresses accuracy ="any|all">
This attribute defines the required accuracy for CC addresses.
any Copy Letters will be created for any CC addresses that are valid. N.B. Invalid CC addresses will not be sent.
all All CC addresses must be valid before any Copy Letters will be created. If just one of the CC addresses is invalid, then the Primary Letter will not be sent, and none of the Copy Letters will be sent.
This attribute is optional, the default is any.
The optional failAction attribute defines how invaid CC addresses are processed. The default is to delete CC letters with invalid addresses. Set the value to reject if you prefer to reject such letters.
<ccSingleAddress> Specifies an identifier containing the text to examine for a single address.
The address will be used to create a Copy Letter regardless of whether it has a CC: prefix. The address is added to the list of any existing CC addresses.
The optional accuracy attribute is applied to the entire list of CC addresses and so is not required here if the <ccAddresses> element already defines it.
The optional failAction attribute is applied to the entire list of CC addresses and so is not required here if the <ccAddresses> element already defines it.
<coverLetterFolder>path</coverLetterFolder> Defines the folder where cover sheets are stored.
If this element is not specified then all instances of the <coverLetter> element must specify a fully-qualified path rather than just a filename.
<coverLetter>filename</coverLetter> Defines the Cover sheet file name.
This should be a single-sheet PDF file with a blank address area and simple text content e.g. "Please see attached letter"
<stripAttachments>true</stripAttachments>Strip all PDF and XML attachments from the Copy Letters.
<stripAttachments stripSupplements="true">
If this attribute is true, then any attachments that were added from within the Print Client will also be stripped.
<ccTemplate>ID-of-Template</ccTemplate>Set the Template ID that will be used when submitting the Copy Letters.
Since Copy Letters are submitted just like any other Letter, changing the Template allows you to perform different input processing on Copy Letters compared to the Primary Letter.
The XML can be executed only during the OnRelease phase.
<loadCustomData/>Load the custom data fields from the database into the letter.
By default, the custom data fields are not loaded into the letter during the onRelease phase. If you wish to use them, e.g. to construct a filename, you must specify this element.
<makePdfFileCopy> Make a copy of the letter PDF file with the specified folder and filename.
<makePdfFileCopy folderName="identifier-name1" fileName="identifier-name2">
These two attributes define the full pathname of the file copy. The folderName identifier must contain a fully-qualified, rooted path to an existing folder. The fileName identifier must contain a valid filename, which may be prefixed with a partial path. The folderName and the fileName are concatenated together to make the destination file path.
A unique marker can be appended to the filename if required, to avoid name clashes.
<makePdfFileCopy includeUnique="random|time|timeMs">
This attribute is optional and appends a suffix to the filename to ensure it is unique. The options are:
random Appends an 11-character random string, e.g. ptgslsn2gpl
time Appends the current time, e.g. 143504
timeMs Appends the current time with milliseconds, e.g. 143504899
Operation
Firstly the CarbonCopy Attachment takes the identifier text or scans the region of the Primary Letter defined in the <ccAddresses> and <ccSingleAddress> elements. An identifier is the preferred approach because it supports the multiPage attribute, which is likely to be needed for CC address scanning.
If no CC addresses are found, the CarbonCopy Attachment does not perform any further processing.
The CC addresses are checked for accuracy. If all CC addresses are valid then processing continues. If one or more CC addresses are invalid, then the action taken depends on the required CC address accuracy as defined above.
Copy Letters are submitted into HybridMail pre-pended with a Cover Sheet. This should be a single-sheet PDF file with a blank address area and simple text content e.g. "Please see attached letter"
A Copy Letter may end up not being sent. This may mean that the Copy Letter was accepted but moved to the user's Rejected queue, or that the Copy Letter was blocked and deleted, depending on how the address accuracy action is configured for the Organisation that created the Primary Letter.
Copy Letters are submitted into HybridMail in the same manner as any other Letter. Therefore any input processing (e.g. XML scripts) is performed in the usual manner.
All Copy Letters are marked as Auto-Generated. CarbonCopy attachment processing is ignored for Auto-Generated letters, so there is no possibility of Copy Letters themselves generating further Copy letters.
Examples
Scan pages 1 to 3 for CC addresses, prepend a cover letter and set the template (differently for invoices).
<mkzAttachment type="CarbonCopy">
<onSubmit>
<setIdentifier name="allccaddr" scan="6,3,120,281" multiPage="1-3" insertNewLine="true" />
<ccAddresses identifier="allccaddr" accuracy="any" />
<stripAttachments stripSupplements="true">true</stripAttachments>
<coverLetterFolder>C:\Proformas\CoverLetters</coverLetterFolder>
<coverLetter>CoverLetter.pdf</coverLetter>
<ccTemplate>83</ccTemplate>
<!-- for invoices, use a different template and cover letter -->
<setIdentifier name="primaryLetterType" scan="0,0,100,20" />
<if identifier="primaryLetterType" contains="invoice">
<coverLetter>CoverLetterInvoice.pdf</coverLetter>
<ccTemplate>84</ccTemplate>
</if>
</onSubmit>
</mkzAttachment>